@bendyline/squisq 1.4.0 → 1.5.0

package/dist/{Doc-BeSeH2iX.d.ts → Doc-BsMkmzH8.d.ts}

@@ -1,4 +1,89 @@
-import { M as MarkdownBlockNode, p as MarkdownHeading } from './types-BdZkdJ3z.js';
+import { Z as Transition, $ as TransitionType, M as MarkdownBlockNode, q as MarkdownHeading } from './types-DlAZ7MW4.js';
+
+/**
+ * Media-clip timing model.
+ *
+ * An additive layer on top of the legacy sequential `Doc.audio.segments[]`
+ * narration track. A {@link MediaClip} is a piece of audio or video whose
+ * timing is expressed *relative to its parent block* (or the whole document),
+ * with an optional `startAt` offset and an optional `spillover` past the
+ * block's end. {@link resolveMediaSchedule} flattens these into absolute,
+ * doc-timeline `ScheduledClip`s that playback and export consume.
+ *
+ * Authoring: a body-level `{[audio …]}` / `{[video …]}` annotation inside a
+ * block becomes a `block.media` clip; the same annotation in the preamble
+ * (before the first heading) with `anchor=document` becomes a
+ * `doc.documentMedia` clip that spans the whole timeline.
+ */
+
+/**
+ * A timed piece of media attached to a block (or the document).
+ */
+interface MediaClip {
+    /** Stable id (for React keys and timeline selection). */
+    id: string;
+    /** Source path (mp3/mp4/…), relative to the article media dir. */
+    src: string;
+    kind: 'audio' | 'video';
+    /**
+     * Seconds from the parent block's start when this clip begins. For an
+     * `anchor='document'` clip, seconds from the document start. Default 0.
+     */
+    startAt: number;
+    /** Source in-point within the file (seconds). Default 0. */
+    clipStart?: number;
+    /** Source out-point within the file (seconds). Default: file/block end. */
+    clipEnd?: number;
+    /**
+     * When false (default) the clip stops at its block's end. When true it
+     * keeps playing past the block boundary until the clip itself finishes.
+     * Ignored for `anchor='document'` clips (they already span the timeline).
+     */
+    spillover?: boolean;
+    /**
+     * `'block'` (default) — timed relative to the parent block. `'document'` —
+     * timed relative to the document start and able to span every block.
+     */
+    anchor: 'block' | 'document';
+    /**
+     * 1-based source line of the authoring annotation, when derived from
+     * markdown. Enables round-tripping edits (e.g. the timeline editor rewriting
+     * `startAt`) back to the exact line. Absent for programmatically built clips.
+     */
+    sourceLine?: number;
+}
+/**
+ * A {@link MediaClip} resolved to absolute document-timeline coordinates.
+ * Produced by {@link resolveMediaSchedule}; consumed by the playback
+ * scheduler and the MP4 export.
+ */
+interface ScheduledClip {
+    id: string;
+    src: string;
+    kind: 'audio' | 'video';
+    /** Absolute doc-timeline second the clip starts. */
+    absoluteStart: number;
+    /** Absolute doc-timeline second the clip ends (exclusive). */
+    absoluteEnd: number;
+    /** Source in-point to seek to at `absoluteStart`. */
+    sourceIn: number;
+    anchor: 'block' | 'document';
+    /** Owning block id for block-anchored clips (for video re-homing/export). */
+    blockId?: string;
+    /** 1-based source line of the authoring annotation, when known. */
+    sourceLine?: number;
+}
+/**
+ * Flatten every block clip and document clip into absolute-timed
+ * `ScheduledClip`s. Pure — depends only on `doc`.
+ */
+declare function resolveMediaSchedule(doc: Doc): ScheduledClip[];
+/**
+ * Total playback duration including any media that spills past the last
+ * block (or audio segment). Export uses this for the frame count and the
+ * player for its effective timeline length.
+ */
+declare function getDocPlaybackDuration(doc: Doc): number;
 
 /**
  * Viewport Configuration
@@ -158,237 +243,6 @@ declare function getSafeTextBounds(orientation: ViewportOrientation): {
     bottom: string;
 };
 
-/**
- * Theme System
- *
- * A Theme bundles color palette, typography, visual style, render-style
- * algorithm, and per-block color schemes into one JSON-serializable object.
- *
- * Built-in themes and customizer-authored themes share this exact schema.
- * Customizer-authored themes additionally specify `seedColors` so the few
- * fields the user picked can be re-edited later; built-ins typically omit
- * `seedColors` and ship with explicit `colors` already filled in.
- *
- * Design principles:
- * - Fully JSON-serializable. No functions; no raw CSS font strings.
- * - Font families are structured `FontFamily` references resolved by
- *   `resolveFontFamily()` at render time.
- * - Doc carries an optional `themeId`; resolution happens at render time
- *   via `resolveTheme(id)`.
- * - `createTheme` deep-merges a base theme with partial overrides;
- *   `compileTheme` fills in defaults and derives missing color slots from
- *   `seedColors`; both produce a complete `Theme`.
- */
-
-/** Current Theme schema version. Bump on breaking changes; loader migrates. */
-declare const THEME_SCHEMA_VERSION: "1";
-type ThemeSchemaVersion = typeof THEME_SCHEMA_VERSION;
-/**
- * Core color palette for a theme. Every color is a `#rrggbb` hex string.
- */
-interface ThemeColorPalette {
-    /** Primary accent color */
-    primary: string;
-    /** Secondary accent color */
-    secondary: string;
-    /** Background color (typically dark) */
-    background: string;
-    /** Lighter background for contrast panels */
-    backgroundLight: string;
-    /** Main text color */
-    text: string;
-    /** Muted/secondary text color */
-    textMuted: string;
-    /** Highlight/emphasis color */
-    highlight: string;
-    /** Warning/alert color */
-    warning: string;
-}
-/**
- * A named color scheme used by templates for per-block color variation
- * (e.g., statHighlight or sectionHeader).
- */
-interface ThemeColorScheme {
-    /** Background fill */
-    bg: string;
-    /** Primary text tint */
-    text: string;
-    /** Accent / secondary tint */
-    accent: string;
-}
-/**
- * Optional authoring metadata. When present and `colors` is partial,
- * `compileTheme` derives missing color slots from these seeds via OKLCh
- * lightening / darkening. Round-trips a customizer-authored theme back
- * into editable form.
- */
-interface ThemeSeedColors {
-    primary: string;
-    secondary?: string;
-    accent?: string;
-    background?: string;
-    text?: string;
-}
-/** Categorical bucket for a font family — drives default fallback. */
-type FontFamilyKind = 'sans' | 'serif' | 'mono' | 'display';
-/**
- * Structured reference to a font family. Either a curated stack id (looked
- * up in `AVAILABLE_FONT_STACKS`) or a custom user-supplied name with a
- * structured fallback bucket. Themes never carry raw CSS family strings.
- */
-type FontFamily = {
-    stackId: string;
-} | {
-    custom: {
-        name: string;
-        fallback: 'serif' | 'sans-serif' | 'monospace' | 'system-ui';
-    };
-};
-/**
- * Typography settings for a theme.
- */
-interface ThemeTypography {
-    /** Font family for body / description text */
-    bodyFont: FontFamily;
-    /** Font family for titles and headings */
-    titleFont: FontFamily;
-    /** Font family for code / monospaced text (optional) */
-    monoFont?: FontFamily;
-    /** Multiplier applied to LayoutHints.titleScale (default 1.0) */
-    titleScale?: number;
-    /** Multiplier applied to LayoutHints.bodyScale (default 1.0) */
-    bodyScale?: number;
-    /** Default body line height (default 1.4) */
-    lineHeight?: number;
-    /** Default title line height */
-    titleLineHeight?: number;
-    /** Default title font weight */
-    titleWeight?: 'normal' | 'bold';
-}
-/**
- * Global visual-style knobs that templates consult.
- */
-interface ThemeStyle {
-    /** Default border radius for cards / shapes (px) */
-    borderRadius?: number;
-    /** Whether templates should default to text shadows */
-    textShadow?: boolean;
-    /** Darkness of overlay on image-backed blocks (0–1) */
-    overlayOpacity?: number;
-    /** Multiplier on all animation durations (1.0 = normal, <1 faster, >1 slower) */
-    animationSpeed?: number;
-    /** Default horizontal padding for text (percentage string, e.g. "5%") */
-    blockPadding?: string;
-}
-/**
- * Render-style algorithm preset. Controls layout tweaks, default animations,
- * transitions, and per-template behavioral hints.
- */
-interface RenderStyle {
-    /** Identifier for this algorithmic approach (e.g. "documentary", "magazine") */
-    name: string;
-    /** Partial overrides merged onto the orientation-based LayoutHints */
-    layoutOverrides?: Partial<LayoutHints>;
-    /** Default entrance animation for text layers */
-    defaultTextAnimation?: AnimationType;
-    /** Default animation for background / image layers */
-    defaultImageAnimation?: AnimationType;
-    /** Whether to apply Ken Burns ambient motion to images by default */
-    ambientMotion?: boolean;
-    /** Default block-to-block transition */
-    defaultTransition?: {
-        type: TransitionType;
-        duration?: number;
-    };
-    /**
-     * Per-template behavioral hints. Keys are template names, values are
-     * string/number/boolean maps that templates can read to vary their output.
-     * Templates that consume hints publish a `hintSchema` export documenting
-     * the keys they recognise.
-     */
-    templateHints?: Record<string, Record<string, string | number | boolean>>;
-}
-/**
- * A complete, JSON-serializable theme definition. Built-in and customizer-
- * authored themes share this exact shape.
- */
-interface Theme {
-    /** Schema version. Always '1' for now. */
-    schemaVersion: ThemeSchemaVersion;
-    /** Unique identifier (e.g. "documentary") */
-    id: string;
-    /** Human-readable display name */
-    name: string;
-    /** Short description for theme pickers */
-    description?: string;
-    /** Optional authoring seeds (customizer fills these; built-ins typically omit) */
-    seedColors?: ThemeSeedColors;
-    /** Color palette */
-    colors: ThemeColorPalette;
-    /** Typography settings */
-    typography: ThemeTypography;
-    /** Global visual-style knobs */
-    style: ThemeStyle;
-    /** Algorithmic render-style preset */
-    renderStyle: RenderStyle;
-    /**
-     * Named color schemes for per-block color variation.
-     * Templates reference these by name (e.g. "blue", "warm").
-     */
-    colorSchemes: Record<string, ThemeColorScheme>;
-    /** Optional persistent layers baked into the theme */
-    persistentLayers?: PersistentLayerConfig;
-}
-/**
- * Recursively makes every property optional.
- */
-type DeepPartial<T> = {
-    [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P];
-};
-/**
- * Create a new theme by deep-merging overrides onto a base theme.
- * The returned theme gets its own `id` if one is provided in overrides,
- * otherwise keeps the base theme's `id` suffixed with "-custom".
- */
-declare function createTheme(base: Theme, overrides: DeepPartial<Theme>): Theme;
-/**
- * A Surface Scheme is the light/dark axis, orthogonal to the editorial
- * identity of a Theme. A Theme chooses voice (serif vs sans, muted vs
- * bold, documentary vs magazine); a SurfaceScheme chooses what the paper
- * looks like. Any theme can render on either surface.
- */
-interface SurfaceScheme {
-    /** Identifier — 'light', 'dark', or a custom id. */
-    id: string;
-    background: string;
-    backgroundLight: string;
-    text: string;
-    textMuted: string;
-}
-/** Near-white paper with dark text — standard light mode. */
-declare const LIGHT_SURFACE: SurfaceScheme;
-/** Dark charcoal paper with light text — standard dark mode. */
-declare const DARK_SURFACE: SurfaceScheme;
-/**
- * Overlay a SurfaceScheme's surface colors onto a Theme's palette,
- * leaving everything else (primary, highlight, warning, typography,
- * style, renderStyle, colorSchemes) untouched.
- */
-declare function applySurface(theme: Theme, surface: SurfaceScheme): Theme;
-/**
- * Register a Theme so it can be looked up by id via `resolveTheme(id)`.
- * Lets `Doc.themeId` round-trip through Doc serialization for custom themes.
- *
- * Registered themes take precedence over built-ins with the same id.
- */
-declare function registerTheme(theme: Theme): void;
-/** Remove a previously registered theme. */
-declare function unregisterTheme(id: string): void;
-/** Snapshot of all currently registered (non-built-in) themes. */
-declare function getRegisteredThemes(): Theme[];
-/** @internal — used by themeLibrary's `resolveTheme` to check the registry first. */
-declare function lookupRegisteredTheme(id: string | undefined): Theme | undefined;
-
 /**
  * Block Templates Schema
  *
@@ -477,6 +331,12 @@ interface BaseTemplateBlock {
      * Used with sourceStartTime to precisely position the block.
      */
     sourceDuration?: number;
+    /**
+     * Per-block override for the theme's photographic image grade
+     * (`theme.style.imageTreatment`). `'none'` opts this block's imagery out;
+     * a treatment type forces that grade regardless of the theme.
+     */
+    imageTreatment?: 'none' | 'mono' | 'duotone' | 'warm' | 'cool';
 }
 /**
  * Title block - doc intro with large title and subtitle.
@@ -826,6 +686,75 @@ interface VideoPullQuoteInput extends BaseTemplateBlock {
         license?: string;
     };
 }
+/**
+ * Diagram block - renders child headings as a node-and-edge diagram.
+ *
+ * Unlike other templates, the diagram template reads its content from
+ * the parent block's `children` (passed via `context.children`) — each
+ * child heading becomes a node, positioned by its `x`/`y` and connected
+ * by its `connectsTo`. Per-diagram options on this input control overall
+ * appearance; per-node data lives on the child blocks themselves.
+ */
+interface DiagramBlockInput extends BaseTemplateBlock {
+    template: 'diagram';
+    /** Optional diagram title displayed above the canvas. */
+    title?: string;
+    /** Color scheme for nodes and edges. */
+    colorScheme?: ColorScheme;
+    /** Node shape style (default: 'rounded'). */
+    nodeShape?: 'rounded' | 'rect' | 'pill';
+    /** Edge routing (default: 'curved'). */
+    edgeStyle?: 'curved' | 'straight' | 'orthogonal';
+    /** Marker at each edge's start (default: 'none'). */
+    startStyle?: MarkerStyle;
+    /** Marker at each edge's end (default: 'arrow'). */
+    endStyle?: MarkerStyle;
+    /** Edge line style (default: 'solid'). */
+    lineStyle?: 'solid' | 'dashed' | 'dotted';
+}
+/**
+ * Free-form 2D canvas block (`layout`). Like `drawing`/`diagram`, the
+ * `layout` template is a children-driven container: each child heading is
+ * one absolutely-positioned layer (`{[text …]}` / `{[rectangle …]}` /
+ * `{[image …]}`), read from `context.children`. A text box's content is the
+ * child's body markdown. Backed by the `layoutBlock` template.
+ *
+ * (Legacy documents stored layers as a base64-JSON `layers=` param on the
+ * heading; the editor auto-migrates those to child sub-blocks on first edit.)
+ */
+interface RawLayersInput extends BaseTemplateBlock {
+    template: 'layout';
+}
+/**
+ * Drawing block — renders child headings as free-form shapes on a canvas.
+ *
+ * Like `diagram`, the drawing template reads its content from the parent
+ * block's `children` (passed via `context.children`). Each child heading
+ * is a shape: its `{[shape …]}` annotation names the primitive
+ * (`rectangle`/`rect`, `circle`, `line`, `arrow`, `path`, `text`) and
+ * carries geometry/style as params; its `{#id}` makes it referenceable;
+ * its heading text is the shape label and its body text an optional
+ * sublabel. Connectors (`line`/`arrow` with `from`/`to`) join shapes by id.
+ *
+ * Coordinates are author-defined units; the template fits the bounding box
+ * of all shapes to the viewport (same scaling as `diagram`), so authors
+ * don't have to think in absolute pixels.
+ *
+ * Legacy drawings authored visually persist their `Layer[]` as a base64
+ * `layers="…"` Pandoc param instead of children; the template decodes and
+ * returns those directly when no children are present (see `drawingBlock`).
+ */
+interface DrawingBlockInput extends BaseTemplateBlock {
+    template: 'drawing';
+    /** Optional title displayed above the canvas. */
+    title?: string;
+    /** Color scheme for shapes that don't pin their own fill/stroke. */
+    colorScheme?: ColorScheme;
+    /** Default fill for shapes that don't specify one (default: 'none'). */
+    fill?: string;
+    /** Default stroke for shapes that don't specify one (default: theme text). */
+    stroke?: string;
+}
 /**
  * Data table - renders a themed table with headers and rows.
  * Ideal for structured data, comparisons, and reference information.
@@ -846,7 +775,7 @@ interface DataTableInput extends BaseTemplateBlock {
 /**
  * Union of all template block types.
  */
-type TemplateBlock = TitleBlockInput | SectionHeaderInput | StatHighlightInput | QuoteBlockInput | FactCardInput | TwoColumnInput | DateEventInput | ImageWithCaptionInput | LeftFeatureInput | RightFeatureInput | MapBlockInput | FullBleedQuoteInput | ListBlockInput | PhotoGridInput | DefinitionCardInput | ComparisonBarInput | PullQuoteInput | VideoWithCaptionInput | VideoPullQuoteInput | DataTableInput;
+type TemplateBlock = TitleBlockInput | SectionHeaderInput | StatHighlightInput | QuoteBlockInput | FactCardInput | TwoColumnInput | DateEventInput | ImageWithCaptionInput | LeftFeatureInput | RightFeatureInput | MapBlockInput | FullBleedQuoteInput | ListBlockInput | PhotoGridInput | DefinitionCardInput | ComparisonBarInput | PullQuoteInput | VideoWithCaptionInput | VideoPullQuoteInput | DataTableInput | DiagramBlockInput | DrawingBlockInput | RawLayersInput;
 /**
  * A block can be either a raw Block or a TemplateBlock.
  */
@@ -874,6 +803,20 @@ interface TemplateContext {
     orientation: ViewportOrientation;
     /** Layout hints for this orientation */
     layout: LayoutHints;
+    /**
+     * The block's direct children (set by `getLayers` when the block has
+     * `children`). Most templates ignore this; aggregate templates like
+     * `diagram` consume it to render each child as part of their output.
+     */
+    children?: Block[];
+    /**
+     * The source block being expanded. Used by user-defined custom
+     * templates so the token resolver can substitute `{title}`,
+     * `{content}`, `{children}`, and `{image:N}` against the block's
+     * data at render time. Built-in templates ignore this and rely on
+     * their typed `input` parameters instead.
+     */
+    block?: Block;
 }
 /**
  * Create a template context with viewport-derived values.
@@ -929,11 +872,11 @@ interface PersistentLayerTemplate {
 /**
  * Available persistent layer template types.
  */
-type PersistentLayerTemplateType = 'solidBackground' | 'gradientBackground' | 'imageBackground' | 'patternBackground' | 'titleCaption' | 'cornerBranding' | 'progressIndicator';
+type PersistentLayerTemplateType = 'solidBackground' | 'gradientBackground' | 'imageBackground' | 'patternBackground' | 'vignette' | 'ambientGradient' | 'titleCaption' | 'cornerBranding' | 'progressIndicator';
 /**
  * Union of all persistent layer template configs.
  */
-type PersistentLayerTemplateConfig = SolidBackgroundConfig | GradientBackgroundConfig | ImageBackgroundConfig | PatternBackgroundConfig | TitleCaptionConfig | CornerBrandingConfig | ProgressIndicatorConfig;
+type PersistentLayerTemplateConfig = SolidBackgroundConfig | GradientBackgroundConfig | ImageBackgroundConfig | PatternBackgroundConfig | VignetteConfig | AmbientGradientConfig | TitleCaptionConfig | CornerBrandingConfig | ProgressIndicatorConfig;
 /**
  * Solid color background.
  */
@@ -980,6 +923,30 @@ interface PatternBackgroundConfig {
     /** Pattern scale multiplier */
     scale?: number;
 }
+/**
+ * Soft radial vignette (top layer) — transparent center darkening toward
+ * the frame edges. The classic film-look framing device.
+ */
+interface VignetteConfig {
+    type: 'vignette';
+    /** Edge darkness 0-1 (default 0.3). */
+    strength?: number;
+    /** Vignette color (default black). */
+    color?: string;
+}
+/**
+ * Slowly drifting surface gradient (bottom layer). Colors default to the
+ * theme's surface family at expansion time.
+ */
+interface AmbientGradientConfig {
+    type: 'ambientGradient';
+    /** Gradient start color. */
+    from?: string;
+    /** Gradient end color. */
+    to?: string;
+    /** Drift loop duration in seconds (default 40). */
+    duration?: number;
+}
 /**
  * Title caption overlay (article title in corner).
  */
@@ -1024,20 +991,339 @@ interface ProgressIndicatorConfig {
 }
 
 /**
- * Doc Schema
+ * Theme System
  *
- * Defines the JSON format for AI-scriptable visual docs that accompany
- * audio narration. A Doc describes a sequence of animated blocks
- * with text overlays, images, and transitions synchronized to audio.
+ * A Theme bundles color palette, typography, visual style, render-style
+ * algorithm, and per-block color schemes into one JSON-serializable object.
  *
- * The format is designed to be:
- * 1. AI-generatable - Claude can create scripts from article content
- * 2. Browser-renderable - SVG + CSS animations (ES2015 compatible)
- * 3. Video-exportable - Frame-by-frame capture via Playwright
+ * Built-in themes and customizer-authored themes share this exact schema.
+ * Customizer-authored themes additionally specify `seedColors` so the few
+ * fields the user picked can be re-edited later; built-ins typically omit
+ * `seedColors` and ship with explicit `colors` already filled in.
  *
- * Timing: Blocks are timed to match narration audio segments. Each article
- * has 3-6 MP3 files (intro + sections), and blocks are grouped by segment.
+ * Design principles:
+ * - Fully JSON-serializable. No functions; no raw CSS font strings.
+ * - Font families are structured `FontFamily` references resolved by
+ *   `resolveFontFamily()` at render time.
+ * - Doc carries an optional `themeId`; resolution happens at render time
+ *   via `resolveTheme(id)`.
+ * - `createTheme` deep-merges a base theme with partial overrides;
+ *   `compileTheme` fills in defaults and derives missing color slots from
+ *   `seedColors`; both produce a complete `Theme`.
+ */
+
+/** Current Theme schema version. Bump on breaking changes; loader migrates. */
+declare const THEME_SCHEMA_VERSION: "1";
+type ThemeSchemaVersion = typeof THEME_SCHEMA_VERSION;
+/**
+ * Frontmatter key under which a document inlines its custom Theme
+ * definitions. The theme analog of `FRONTMATTER_CUSTOM_TEMPLATES_KEY`
+ * (custom block templates). See `doc/customThemesFrontmatter.ts` for the
+ * codec and `doc/resolveDocTheme.ts` for doc-scoped resolution.
+ */
+declare const FRONTMATTER_CUSTOM_THEMES_KEY = "squisq-custom-themes";
+/**
+ * Core color palette for a theme. Every color is a `#rrggbb` hex string.
+ */
+interface ThemeColorPalette {
+    /** Primary accent color */
+    primary: string;
+    /** Secondary accent color */
+    secondary: string;
+    /** Background color (typically dark) */
+    background: string;
+    /** Lighter background for contrast panels */
+    backgroundLight: string;
+    /** Main text color */
+    text: string;
+    /** Muted/secondary text color */
+    textMuted: string;
+    /** Highlight/emphasis color */
+    highlight: string;
+    /** Warning/alert color */
+    warning: string;
+}
+/**
+ * A named color scheme used by templates for per-block color variation
+ * (e.g., statHighlight or sectionHeader).
+ */
+interface ThemeColorScheme {
+    /** Background fill */
+    bg: string;
+    /** Primary text tint */
+    text: string;
+    /** Accent / secondary tint */
+    accent: string;
+}
+/**
+ * Optional authoring metadata. When present and `colors` is partial,
+ * `compileTheme` derives missing color slots from these seeds via OKLCh
+ * lightening / darkening. Round-trips a customizer-authored theme back
+ * into editable form.
  */
+interface ThemeSeedColors {
+    primary: string;
+    secondary?: string;
+    accent?: string;
+    background?: string;
+    text?: string;
+}
+/** Categorical bucket for a font family — drives default fallback. */
+type FontFamilyKind = 'sans' | 'serif' | 'mono' | 'display';
+/**
+ * Structured reference to a font family. Either a curated stack id (looked
+ * up in `AVAILABLE_FONT_STACKS`) or a custom user-supplied name with a
+ * structured fallback bucket. Themes never carry raw CSS family strings.
+ */
+type FontFamily = {
+    stackId: string;
+} | {
+    custom: {
+        name: string;
+        fallback: 'serif' | 'sans-serif' | 'monospace' | 'system-ui';
+    };
+};
+/**
+ * Typography settings for a theme.
+ */
+interface ThemeTypography {
+    /** Font family for body / description text */
+    bodyFont: FontFamily;
+    /** Font family for titles and headings */
+    titleFont: FontFamily;
+    /** Font family for code / monospaced text (optional) */
+    monoFont?: FontFamily;
+    /** Multiplier applied to LayoutHints.titleScale (default 1.0) */
+    titleScale?: number;
+    /** Multiplier applied to LayoutHints.bodyScale (default 1.0) */
+    bodyScale?: number;
+    /** Default body line height (default 1.4) */
+    lineHeight?: number;
+    /** Default title line height */
+    titleLineHeight?: number;
+    /** Default title font weight */
+    titleWeight?: 'normal' | 'bold';
+}
+/**
+ * Global visual-style knobs that templates consult.
+ */
+interface ThemeStyle {
+    /** Default border radius for cards / shapes (px) */
+    borderRadius?: number;
+    /** Whether templates should default to text shadows */
+    textShadow?: boolean;
+    /** Darkness of overlay on image-backed blocks (0–1) */
+    overlayOpacity?: number;
+    /** Multiplier on all animation durations (1.0 = normal, <1 faster, >1 slower) */
+    animationSpeed?: number;
+    /** Default horizontal padding for text (percentage string, e.g. "5%") */
+    blockPadding?: string;
+    /**
+     * Photographic grade applied to template imagery (full-bleed photos,
+     * feature halves, accent strips) so photos look native to the theme.
+     * Duotone tints default to the theme primary. Blocks opt out per
+     * template via `imageTreatment: 'none'`.
+     */
+    imageTreatment?: ImageTreatment;
+}
+/**
+ * Render-style algorithm preset. Controls layout tweaks, default animations,
+ * transitions, and per-template behavioral hints.
+ */
+interface RenderStyle {
+    /** Identifier for this algorithmic approach (e.g. "documentary", "magazine") */
+    name: string;
+    /** Partial overrides merged onto the orientation-based LayoutHints */
+    layoutOverrides?: Partial<LayoutHints>;
+    /** Default entrance animation for text layers */
+    defaultTextAnimation?: AnimationType;
+    /** Default animation for background / image layers */
+    defaultImageAnimation?: AnimationType;
+    /** Whether to apply Ken Burns ambient motion to images by default */
+    ambientMotion?: boolean;
+    /** Default block-to-block transition */
+    defaultTransition?: {
+        type: TransitionType;
+        duration?: number;
+    };
+    /**
+     * Per-template behavioral hints. Keys are template names, values are
+     * string/number/boolean maps that templates can read to vary their output.
+     * Templates that consume hints publish a `hintSchema` export documenting
+     * the keys they recognise.
+     */
+    templateHints?: Record<string, Record<string, string | number | boolean>>;
+}
+/**
+ * A complete, JSON-serializable theme definition. Built-in and customizer-
+ * authored themes share this exact shape.
+ */
+interface Theme {
+    /** Schema version. Always '1' for now. */
+    schemaVersion: ThemeSchemaVersion;
+    /** Unique identifier (e.g. "documentary") */
+    id: string;
+    /** Human-readable display name */
+    name: string;
+    /** Short description for theme pickers */
+    description?: string;
+    /**
+     * Id of the theme this custom theme was derived from, if any. Recorded
+     * by `compileTheme({ base })` so a customizer can re-open the theme and
+     * re-inherit the base's render style / color schemes / typography.
+     * Absent on built-ins.
+     */
+    basedOn?: string;
+    /** Optional authoring seeds (customizer fills these; built-ins typically omit) */
+    seedColors?: ThemeSeedColors;
+    /** Color palette */
+    colors: ThemeColorPalette;
+    /** Typography settings */
+    typography: ThemeTypography;
+    /** Global visual-style knobs */
+    style: ThemeStyle;
+    /** Algorithmic render-style preset */
+    renderStyle: RenderStyle;
+    /**
+     * Named color schemes for per-block color variation.
+     * Templates reference these by name (e.g. "blue", "warm").
+     */
+    colorSchemes: Record<string, ThemeColorScheme>;
+    /** Optional persistent layers baked into the theme */
+    persistentLayers?: PersistentLayerConfig;
+}
+/**
+ * Recursively makes every property optional.
+ */
+type DeepPartial<T> = {
+    [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P];
+};
+/**
+ * Create a new theme by deep-merging overrides onto a base theme.
+ * The returned theme gets its own `id` if one is provided in overrides,
+ * otherwise keeps the base theme's `id` suffixed with "-custom".
+ */
+declare function createTheme(base: Theme, overrides: DeepPartial<Theme>): Theme;
+/**
+ * A Surface Scheme is the light/dark axis, orthogonal to the editorial
+ * identity of a Theme. A Theme chooses voice (serif vs sans, muted vs
+ * bold, documentary vs magazine); a SurfaceScheme chooses what the paper
+ * looks like. Any theme can render on either surface.
+ */
+interface SurfaceScheme {
+    /** Identifier — 'light', 'dark', or a custom id. */
+    id: string;
+    background: string;
+    backgroundLight: string;
+    text: string;
+    textMuted: string;
+}
+/** Near-white paper with dark text — standard light mode. */
+declare const LIGHT_SURFACE: SurfaceScheme;
+/** Dark charcoal paper with light text — standard dark mode. */
+declare const DARK_SURFACE: SurfaceScheme;
+/**
+ * Overlay a SurfaceScheme's surface colors onto a Theme's palette,
+ * leaving everything else (primary, highlight, warning, typography,
+ * style, renderStyle, colorSchemes) untouched.
+ */
+declare function applySurface(theme: Theme, surface: SurfaceScheme): Theme;
+/**
+ * Register a Theme so it can be looked up by id via `resolveTheme(id)`.
+ * Lets `Doc.themeId` round-trip through Doc serialization for custom themes.
+ *
+ * Registered themes take precedence over built-ins with the same id.
+ */
+declare function registerTheme(theme: Theme): void;
+/** Remove a previously registered theme. */
+declare function unregisterTheme(id: string): void;
+/** Snapshot of all currently registered (non-built-in) themes. */
+declare function getRegisteredThemes(): Theme[];
+/** @internal — used by themeLibrary's `resolveTheme` to check the registry first. */
+declare function lookupRegisteredTheme(id: string | undefined): Theme | undefined;
+
+/**
+ * Custom Templates Schema
+ *
+ * User-defined block layout templates. The author designs a visual
+ * layout once (in the editor's TemplateDesigner) and saves it as a
+ * `CustomTemplateDefinition`. The definition lives either in the
+ * document's frontmatter (per-doc, portable, ships with the markdown)
+ * or in the user's local library (cross-doc reuse via localStorage).
+ *
+ * A custom template's content is just a `Layer[]` — the same shape that
+ * built-in templates emit at expansion time. The novel bit is
+ * *placeholder tokens*: TextLayer / ImageLayer content fields may carry
+ * strings like `{title}`, `{content}`, `{children}`, or `{image:N}`
+ * that the resolver (see `doc/templates/tokens/resolveTokens.ts`)
+ * substitutes against the source Block at render time.
+ *
+ * Responsiveness model: every numeric position field in `layers` is
+ * stored as a `%`-string relative to `viewport`, so the same template
+ * renders correctly at any of Squisq's viewport presets (landscape,
+ * portrait, square). The `viewport` field itself is purely an
+ * authoring-time reference — it tells the designer canvas which aspect
+ * ratio to mount with, and the thumbnail renderer which viewBox to use.
+ */
+
+/**
+ * A single user-defined template. Stored in `Doc.customTemplates`
+ * (frontmatter-backed) or in the user's local library.
+ */
+interface CustomTemplateDefinition {
+    /**
+     * Stable id used in heading annotations (`### Foo {[name]}`). Must be
+     * a slug — lowercase alphanumerics, hyphens. The picker enforces
+     * uniqueness within a (doc + library) merged namespace.
+     */
+    name: string;
+    /** Human-readable label shown in the template picker. */
+    label: string;
+    /** Optional one-sentence description for the picker card. */
+    description?: string;
+    /**
+     * Authoring viewport — the canvas size the designer drew against.
+     * Stored so the designer and thumbnail renderer can reproduce the
+     * same canvas. Layer positions are stored as `%`-strings, so the
+     * actual render-time viewport can differ from this without breaking
+     * the layout. Defaults to 1920×1080 landscape.
+     */
+    viewport: {
+        width: number;
+        height: number;
+    };
+    /**
+     * The visual content. Every `position.x` / `position.y` /
+     * `position.width` / `position.height` should be a `%`-string at
+     * save time (the designer's normalizePositions step enforces this).
+     *
+     * Tokens supported in v1:
+     *   - TextLayer.content.text — `{title}`, `{content}`, `{children}`,
+     *     `{image:N}` (substitutes the Nth image's alt text)
+     *   - ImageLayer.content.src — `{image:N}` (substitutes the URL)
+     */
+    layers: Layer[];
+}
+/**
+ * Tag value for the YAML frontmatter key that carries inlined custom
+ * template definitions. Exported so the markdown bridge stays in sync.
+ */
+declare const FRONTMATTER_CUSTOM_TEMPLATES_KEY = "squisq-custom-templates";
+
+/**
+ * A directed connection from one block to another.
+ *
+ * Populated from a heading's Pandoc-style `{connectsTo=…}` attribute
+ * (e.g. `## Step 1 {#step1 connectsTo=foo:flow,bar}`). Each item is
+ * `target` or `target:type`. Used by diagram-style layouts that draw
+ * edges between blocks.
+ */
+interface BlockConnection {
+    /** Target block id (matches another block's `id`). */
+    target: string;
+    /** Optional connection type/label (e.g., "flow", "requires"). */
+    type?: string;
+}
 /**
  * Configuration for the Start/resting block shown before playback begins.
  */
@@ -1057,6 +1343,29 @@ interface StartBlockConfig {
     /** License identifier for the hero image */
     heroLicense?: string;
 }
+/**
+ * A structural problem detected while converting or validating a document.
+ *
+ * Diagnostics ride on `Doc.diagnostics` so any consumer — the editor, the
+ * CLI `validate` command, or an agent re-parsing its own output — gets the
+ * same feedback without watching the console. Conversion never throws for
+ * content problems; it degrades gracefully and records a diagnostic.
+ */
+interface DocDiagnostic {
+    /** `error` = the author's intent could not be honored (e.g. unparseable
+     *  data fence); `warning` = something looks wrong but rendering proceeds
+     *  with a fallback (e.g. unknown template name). */
+    severity: 'error' | 'warning';
+    /** Stable machine-readable code (e.g. `unknown-template`, `duplicate-id`,
+     *  `unresolved-connection`, `data-fence-parse`, `missing-asset`). */
+    code: string;
+    /** Human-readable description, including a suggestion when one exists. */
+    message: string;
+    /** Id of the block the problem belongs to, when attributable. */
+    blockId?: string;
+    /** 1-based line number in the markdown source, when known. */
+    line?: number;
+}
 /**
  * A complete visual doc for an article.
  */
@@ -1098,6 +1407,48 @@ interface Doc {
      * Carries rendering hints like `document-render-as` and custom metadata.
      */
     frontmatter?: Record<string, unknown>;
+    /**
+     * User-defined block templates inlined into this doc.
+     *
+     * Populated from the markdown frontmatter key
+     * `squisq-custom-templates`. The template-expansion pipeline
+     * (`expandDocBlocks`) merges these into the registry before walking
+     * blocks, so a heading annotated `{[myhero]}` resolves against a
+     * doc-defined template named `myhero`.
+     *
+     * Library templates (stored in localStorage on the editor side) are
+     * NOT auto-loaded here — applying a library template to a block
+     * copies its definition into this list so the doc remains
+     * self-sufficient for SSR and export.
+     */
+    customTemplates?: CustomTemplateDefinition[];
+    /**
+     * User-defined themes inlined into this doc.
+     *
+     * The theme analog of {@link Doc.customTemplates}. Populated from the
+     * markdown frontmatter key `squisq-custom-themes`. Exactly one is active
+     * at a time — selected by id via `squisq-theme` / {@link Doc.themeId},
+     * the doc-level counterpart of a block's `{[name]}` template annotation —
+     * but the payload is a list so a doc can carry a small catalog and stay
+     * self-sufficient for SSR / export. `resolveThemeForDoc(doc, id)` resolves
+     * against this list first (pure, doc-scoped) before built-ins, mirroring
+     * how `buildRegistry` resolves custom templates.
+     */
+    customThemes?: Theme[];
+    /**
+     * Structural problems found while building this doc (unknown templates,
+     * unparseable data fences, duplicate ids, unresolved connections, …).
+     * Populated by `markdownToDoc()`; extended by `validateMarkdownDoc()`.
+     * Absent when the document is clean.
+     */
+    diagnostics?: DocDiagnostic[];
+    /**
+     * Document-spanning timed media (e.g. a full-length narration MP3/MP4),
+     * authored as a media annotation in the preamble (before the first
+     * heading) with `anchor=document`. Each clip is timed from the document
+     * start and may play across every block. See `resolveMediaSchedule`.
+     */
+    documentMedia?: MediaClip[];
 }
 /**
  * A single block in the doc.
@@ -1109,11 +1460,15 @@ interface Doc {
  * - `children` holds sub-heading blocks (e.g., H2s under an H1)
  */
 interface Block {
-    /** Unique identifier for this block */
+    /** Unique identifier for this block.
+     *  Defaults to a slug derived from the heading text. May be overridden by
+     *  a Pandoc-style `{#custom-id}` attribute on the heading. */
     id: string;
-    /** When this block appears (seconds from start) */
+    /** When this block appears (seconds from start).
+     *  Overridden by a heading attribute `startTime=…` when present. */
     startTime: number;
-    /** How long this block is visible (seconds) */
+    /** How long this block is visible (seconds).
+     *  Overridden by a heading attribute `duration=…` when present. */
     duration: number;
     /** Which audio segment this block belongs to (0-indexed) */
     audioSegment: number;
@@ -1129,6 +1484,13 @@ interface Block {
     transition?: Transition;
     /** Template name that generated this block (for debugging) */
     template?: string;
+    /**
+     * True when `template` was chosen by content-aware auto-picking
+     * (`markdownToDoc`'s `autoTemplates`) rather than authored. Ephemeral:
+     * `docToMarkdown` does not materialize auto-picked templates as heading
+     * annotations, keeping the markdown round-trip lossless.
+     */
+    autoTemplate?: boolean;
     /**
      * Display title for template rendering.
      * Extracted from the sourceHeading when the block is created by markdownToDoc().
@@ -1157,18 +1519,60 @@ interface Block {
      */
     sourceHeading?: MarkdownHeading;
     /**
-     * Template overrides extracted from markdown directives.
-     * For example, `### Data Section {template=chart colorScheme=blue}`
-     * would produce `{ template: 'chart', colorScheme: 'blue' }`.
-     * Allows per-block customization of template selection and parameters.
+     * Template overrides extracted from a heading's `{[templateName key=value]}`
+     * annotation. Only carries template-specific params (e.g. `colorScheme=blue`).
+     * Block-level metadata lives in `x` / `y` / `connectsTo` / `metadata` and is
+     * sourced from the Pandoc-style `{#id .class key=value}` attribute block instead.
      */
     templateOverrides?: Record<string, string>;
+    /**
+     * Structured template inputs sourced from the block's body content:
+     * a ```json data / ```yaml data fence under the heading, or — for the
+     * `dataTable` template — the first GFM table in the section. Unlike
+     * `templateOverrides` (always strings), values here keep their parsed
+     * types (arrays, numbers, nested objects). Merge order at render time:
+     * template defaults → `templateData` → `templateOverrides`.
+     */
+    templateData?: Record<string, unknown>;
+    /**
+     * X coordinate for diagram-style positioning (in author-defined units).
+     * Sourced from a heading attribute `x=…`.
+     */
+    x?: number;
+    /**
+     * Y coordinate for diagram-style positioning (in author-defined units).
+     * Sourced from a heading attribute `y=…`.
+     */
+    y?: number;
+    /**
+     * Outgoing connections to other blocks, by id. Sourced from a heading
+     * attribute `connectsTo=target1,target2:type,target3`.
+     */
+    connectsTo?: BlockConnection[];
+    /**
+     * CSS-style class tokens from a heading's Pandoc attribute (e.g. `{.important .v2}`).
+     * Parsed and stored; downstream consumers may use them for styling or filtering.
+     */
+    classes?: string[];
+    /**
+     * Free-form metadata for heading attribute keys outside the typed registry
+     * (anything that isn't `x` / `y` / `connectsTo` / `startTime` / `duration`).
+     * Values are raw strings exactly as authored.
+     */
+    metadata?: Record<string, string>;
+    /**
+     * Timed media clips attached to this block, authored as body-level
+     * `{[audio …]}` / `{[video …]}` annotations. Each clip is timed relative
+     * to this block's `startTime` (via `startAt`) and optionally spills past
+     * the block's end. See `MediaClip` / `resolveMediaSchedule`.
+     */
+    media?: MediaClip[];
 }
 /**
  * A visual element within a block.
  * Layers are composited back-to-front (first layer is background).
  */
-type Layer = ImageLayer | TextLayer | ShapeLayer | MapLayer | VideoLayer | TableLayer;
+type Layer = ImageLayer | TextLayer | ShapeLayer | PathLayer | MapLayer | VideoLayer | TableLayer;
 interface BaseLayer {
     /** Unique identifier for this layer */
     id: string;
@@ -1177,6 +1581,24 @@ interface BaseLayer {
     /** Animation to apply */
     animation?: Animation;
 }
+/**
+ * Photographic treatment applied to an image layer — a theme-level "grade"
+ * so the same photo looks native in every theme. Rendered as CSS filter
+ * functions, which behave identically in the browser player and headless
+ * frame capture (video/still export).
+ */
+interface ImageTreatment {
+    /**
+     * mono: desaturate toward archival black & white.
+     * duotone: single-hue tint (hue taken from `color`).
+     * warm / cool: gentle temperature grade.
+     */
+    type: 'none' | 'mono' | 'duotone' | 'warm' | 'cool';
+    /** Blend strength 0..1. Default 0.6. */
+    strength?: number;
+    /** Duotone tint color (themes default this to their primary). */
+    color?: string;
+}
 /**
  * Image layer - displays an image with optional Ken Burns effect.
  */
@@ -1193,6 +1615,10 @@ interface ImageLayer extends BaseLayer {
         credit?: string;
         /** License identifier (e.g., 'CC BY-SA 4.0') */
         license?: string;
+        /** Theme-derived photographic grade (see ImageTreatment). */
+        treatment?: ImageTreatment;
+        /** Gaussian blur radius in px (background/atmosphere imagery). */
+        blur?: number;
     };
 }
 /**
@@ -1201,15 +1627,68 @@ interface ImageLayer extends BaseLayer {
 interface TextLayer extends BaseLayer {
     type: 'text';
     content: {
-        /** Text to display (supports \n for line breaks) */
+        /**
+         * Plain text (supports \n for line breaks). Source of truth for plain
+         * consumers — PDF/markdown export, search, accessibility — and the SVG
+         * `<text>` fallback. When `html` is set, this is its plain-text
+         * projection and must be kept in sync.
+         */
         text: string;
+        /**
+         * Optional sanitized **inline** HTML for rich formatting (bold/italic/
+         * links, and — for layout textboxes — headings/lists). When present the
+         * renderer draws it via `<foreignObject>` instead of SVG `<text>`. Treated
+         * as untrusted and re-sanitized at render time. See `RichTextLayer` in
+         * `@bendyline/squisq-react`.
+         */
+        html?: string;
         /** Text styling */
         style: TextStyle;
     };
 }
+/**
+ * A two-stop linear gradient fill, shared by shape/path fills and text
+ * backgrounds. When present it overrides the solid `fill` color.
+ *
+ * `angle` is in degrees: 0 = top→bottom, 90 = left→right, increasing
+ * clockwise. Defaults to 0. Rendered as an SVG `<linearGradient>` in
+ * objectBoundingBox units so it scales with the layer's box.
+ */
+interface LinearGradient {
+    from: string;
+    to: string;
+    angle?: number;
+}
+/** Border line style, mapped to an SVG stroke-dasharray by the renderer. */
+type BorderStyle = 'solid' | 'dashed' | 'dotted';
 /**
  * Shape layer - simple geometric shapes for visual accents.
  */
+/**
+ * Repeating SVG pattern fill for a shape (dots, grid, diagonal lines).
+ * Rendered as a native `<pattern>` def — fully vector and export-safe.
+ */
+interface ShapePattern {
+    kind: 'dots' | 'grid' | 'diagonal';
+    /** Pattern ink color. */
+    color: string;
+    /** Tile size in px (default 24). */
+    size?: number;
+    /** Pattern opacity 0–1 (default 1; tint via a translucent color or this). */
+    opacity?: number;
+}
+/**
+ * Procedural filter applied to a shape. `noise` renders static film grain
+ * via SVG feTurbulence — deliberately not animated so frame capture and
+ * the live player agree.
+ */
+interface ShapeFilter {
+    type: 'noise';
+    /** feTurbulence base frequency (default 0.8 — fine grain). */
+    baseFrequency?: number;
+    /** Grain opacity 0–1 (default 0.05). */
+    opacity?: number;
+}
 interface ShapeLayer extends BaseLayer {
     type: 'shape';
     content: {
@@ -1217,14 +1696,85 @@ interface ShapeLayer extends BaseLayer {
         shape: 'rect' | 'circle' | 'line';
         /** Fill color (CSS color or 'none') */
         fill?: string;
+        /** Fill opacity 0–1 (applies to solid and gradient fills). */
+        fillOpacity?: number;
+        /** Gradient fill; overrides `fill` when set. */
+        gradient?: LinearGradient;
+        /** Repeating pattern fill; overrides `fill`/`gradient` when set. */
+        pattern?: ShapePattern;
+        /** Procedural filter (film grain). */
+        filter?: ShapeFilter;
         /** Stroke color */
         stroke?: string;
         /** Stroke width in pixels */
         strokeWidth?: number;
+        /** Border line style (solid/dashed/dotted). Default solid. */
+        borderStyle?: BorderStyle;
         /** Corner radius for rect */
         borderRadius?: number;
     };
 }
+/**
+ * End-of-line marker style for a path/connector endpoint.
+ * `arrow` is a filled triangle (the classic arrowhead); `open` is a stroked
+ * V; `diamond`/`circle`/`square` are filled glyphs; `none` draws nothing.
+ */
+type MarkerStyle = 'none' | 'arrow' | 'open' | 'diamond' | 'circle' | 'square';
+/**
+ * Path layer - renders an SVG `<path>` for arbitrary curves, connectors,
+ * arrows, or filled regions. Used by the diagram template for edges
+ * between nodes, the drawing template for non-rect/circle/line shapes, and
+ * available to any template that needs a custom geometry.
+ *
+ * The `position` field carries the layer's bounding box (so animations
+ * and clipping work the same as for other layers), but the actual
+ * geometry is encoded in the `d` attribute using absolute SVG path
+ * coordinates relative to the block viewport.
+ */
+interface PathLayer extends BaseLayer {
+    type: 'path';
+    content: {
+        /** SVG path `d` attribute (e.g. "M 10 10 L 90 90"). Absolute viewBox coords. */
+        d: string;
+        /**
+         * Named shape kind (e.g. `'diamond'`, `'star'`, `'arrow-right'`) for
+         * path layers that represent one of Squisq's standard shapes. When
+         * set, the renderer re-derives `d` from the layer's `position` box
+         * (resolved against the viewport) instead of using the stored `d` —
+         * so the shape moves, resizes, and adapts to any aspect ratio like
+         * the native rect/circle/line layers do. Plain paths (connectors,
+         * freehand) leave this unset and keep their absolute `d`.
+         */
+        shapeKind?: string;
+        /** Stroke color (default: theme text color). */
+        stroke?: string;
+        /** Stroke width in pixels (default: 2). */
+        strokeWidth?: number;
+        /** Optional fill color (default: 'none' — pure connectors). */
+        fill?: string;
+        /** Fill opacity 0–1 (applies to solid and gradient fills). */
+        fillOpacity?: number;
+        /** Gradient fill; overrides `fill` when set. */
+        gradient?: LinearGradient;
+        /**
+         * Border line style (solid/dashed/dotted). A convenience over
+         * `dasharray` for named shapes; when set the renderer derives the
+         * dash pattern from it (scaled by stroke width).
+         */
+        borderStyle?: BorderStyle;
+        /** Optional stroke dash pattern (SVG `stroke-dasharray` syntax). */
+        dasharray?: string;
+        /**
+         * Legacy arrowhead flag. Prefer `startMarker`/`endMarker`. When those are
+         * unset, `'end'`/`'start'`/`'both'` render a filled-triangle arrowhead.
+         */
+        arrow?: 'none' | 'end' | 'start' | 'both';
+        /** Marker at the path start (overrides `arrow`). Default: derived from `arrow`. */
+        startMarker?: MarkerStyle;
+        /** Marker at the path end (overrides `arrow`). Default: derived from `arrow`. */
+        endMarker?: MarkerStyle;
+    };
+}
 /**
  * Map layer - displays a geographic map with optional markers.
  *
@@ -1276,6 +1826,16 @@ interface VideoLayer extends BaseLayer {
         clipEnd: number;
         /** Total source video duration (for validation) */
         sourceDuration?: number;
+        /**
+         * Seconds into the owning block before this video begins playing
+         * (the block-relative `startAt`). Default 0 — plays from block start.
+         */
+        startAt?: number;
+        /**
+         * When true, the video keeps playing past the block's end (the
+         * playback scheduler re-homes it to the player level). Default false.
+         */
+        spillover?: boolean;
         /** Video credit / artist name */
         credit?: string;
         /** License identifier (e.g., 'CC BY-SA 4.0') */
@@ -1367,16 +1927,34 @@ interface TextStyle {
     fontFamily?: string;
     /** Font weight */
     fontWeight?: 'normal' | 'bold';
+    /** Font style. Also the inherited baseline for rich `content.html`. */
+    fontStyle?: 'normal' | 'italic';
     /** Text color (CSS color) */
     color: string;
-    /** Text alignment */
+    /** Horizontal text alignment within the layer's position box. */
     textAlign?: 'left' | 'center' | 'right';
+    /**
+     * Vertical alignment of the text within the layer's position box.
+     * Requires a `position.height` to have an effect. When omitted, the
+     * vertical baseline is derived from `position.anchor` (legacy behavior).
+     */
+    verticalAlign?: 'top' | 'middle' | 'bottom';
     /** Line height multiplier */
     lineHeight?: number;
     /** Add drop shadow for readability over images */
     shadow?: boolean;
     /** Background color for text box */
     background?: string;
+    /** Background opacity 0–1 (applies to solid and gradient backgrounds). */
+    backgroundOpacity?: number;
+    /** Gradient background; overrides `background` when set. */
+    backgroundGradient?: LinearGradient;
+    /** Border (stroke) color for the text box. */
+    borderColor?: string;
+    /** Border width in pixels. A border renders when > 0 and a color is set. */
+    borderWidth?: number;
+    /** Border line style (solid/dashed/dotted). Default solid. */
+    borderStyle?: BorderStyle;
     /** Padding around text (pixels) */
     padding?: number;
     /** Maximum number of lines before truncation (adds "..." to last line) */
@@ -1403,16 +1981,6 @@ interface Animation {
  * Available animation types.
  */
 type AnimationType = 'none' | 'fadeIn' | 'fadeOut' | 'slowZoom' | 'zoomIn' | 'zoomOut' | 'panLeft' | 'panRight' | 'typewriter';
-/**
- * Transition between blocks.
- */
-interface Transition {
-    /** Transition type */
-    type: TransitionType;
-    /** Duration in seconds */
-    duration: number;
-}
-type TransitionType = 'cut' | 'fade' | 'dissolve' | 'slideLeft' | 'slideRight';
 /**
  * Audio track configuration.
  * Articles have multiple MP3 segments (intro + sections).
@@ -1459,8 +2027,10 @@ interface CaptionPhrase {
 interface CaptionTrack {
     /** Caption phrases in chronological order */
     phrases: CaptionPhrase[];
-    /** When the captions were generated */
-    generatedAt: string;
+    /** When the captions were generated. Optional so that conversion stays
+     *  deterministic — `markdownToDoc()` only sets it when the caller
+     *  supplies a timestamp via `captionsGeneratedAt`. */
+    generatedAt?: string;
     /** Algorithm version for regeneration detection */
     version: number;
 }
@@ -1525,4 +2095,4 @@ declare function getCaptionAtTime(captions: CaptionTrack | undefined, time: numb
  */
 declare function validateDoc(script: Doc): string[];
 
-export { type RightFeatureInput as $, type AccentImage as A, type Block as B, type CaptionPhrase as C, DARK_SURFACE as D, type LayoutHints as E, type FactCardInput as F, type GradientBackgroundConfig as G, type LeftFeatureInput as H, type ImageBackgroundConfig as I, type ListBlockInput as J, type MapLayer as K, LIGHT_SURFACE as L, type MapBlockInput as M, type MapMarker as N, type MapTileStyle as O, type PatternBackgroundConfig as P, type PersistentLayer as Q, type PersistentLayerConfig as R, type PersistentLayerTemplate as S, type PersistentLayerTemplateConfig as T, type PersistentLayerTemplateType as U, type PhotoGridInput as V, type Position as W, type ProgressIndicatorConfig as X, type PullQuoteInput as Y, type QuoteBlockInput as Z, type RenderStyle as _, type AccentPosition as a, type SectionHeaderInput as a0, type ShapeLayer as a1, type SolidBackgroundConfig as a2, type StartBlockConfig as a3, type StatHighlightInput as a4, type SurfaceScheme as a5, THEME_SCHEMA_VERSION as a6, type TableLayer as a7, type TableLayerStyle as a8, type TemplateBlock as a9, calculateFontScale as aA, createTemplateContext as aB, createTheme as aC, getAspectRatioString as aD, getBlockAtTime as aE, getCaptionAtTime as aF, getLayoutHints as aG, getRegisteredThemes as aH, getSafeTextBounds as aI, getSegmentAtTime as aJ, getTwoColumnPositions as aK, getViewport as aL, getViewportOrientation as aM, isPersistentLayerTemplate as aN, isTemplateBlock as aO, scaledFontSize$1 as aP, lookupRegisteredTheme as aQ, registerTheme as aR, scaledFontSize as aS, unregisterTheme as aT, validateDoc as aU, type TemplateContext as aa, type TemplateFunction as ab, type TemplateRegistry as ac, type TextLayer as ad, type TextStyle as ae, type Theme as af, type ThemeColorPalette as ag, type ThemeColorScheme as ah, type ThemeSchemaVersion as ai, type ThemeSeedColors as aj, type ThemeStyle as ak, type ThemeTypography as al, type TitleBlockInput as am, type TitleCaptionConfig as an, type Transition as ao, type TransitionType as ap, type TwoColumnInput as aq, VIEWPORT_PRESETS as ar, type VideoLayer as as, type VideoPullQuoteInput as at, type VideoWithCaptionInput as au, type ViewportConfig as av, type ViewportOrientation as aw, type ViewportPreset as ax, applySurface as ay, calculateDuration as az, type Animation as b, type AnimationType as c, type AudioBookmark as d, type AudioSegment as e, type AudioTimingData as f, type AudioTrack as g, type CaptionTrack as h, type CaptionWord as i, type ColorScheme as j, type ComparisonBarInput as k, type CornerBrandingConfig as l, DEFAULT_DOC_FONT as m, DEFAULT_TITLE_FONT as n, type DataTableInput as o, type DateEventInput as p, type DeepPartial as q, type DefinitionCardInput as r, type Doc as s, type DocBlock as t, type FontFamily as u, type FontFamilyKind as v, type FullBleedQuoteInput as w, type ImageLayer as x, type ImageWithCaptionInput as y, type Layer as z };
+export { type MediaClip as $, type AccentImage as A, type Block as B, type CaptionPhrase as C, DARK_SURFACE as D, type DrawingBlockInput as E, FRONTMATTER_CUSTOM_TEMPLATES_KEY as F, FRONTMATTER_CUSTOM_THEMES_KEY as G, type FactCardInput as H, type FontFamily as I, type FontFamilyKind as J, type FullBleedQuoteInput as K, type GradientBackgroundConfig as L, type ImageBackgroundConfig as M, type ImageLayer as N, type ImageTreatment as O, type ImageWithCaptionInput as P, LIGHT_SURFACE as Q, type Layer as R, type LayoutHints as S, type LeftFeatureInput as T, type LinearGradient as U, type ListBlockInput as V, type MapBlockInput as W, type MapLayer as X, type MapMarker as Y, type MapTileStyle as Z, type MarkerStyle as _, type AccentPosition as a, getSegmentAtTime as a$, type PathLayer as a0, type PatternBackgroundConfig as a1, type PersistentLayer as a2, type PersistentLayerConfig as a3, type PersistentLayerTemplate as a4, type PersistentLayerTemplateConfig as a5, type PersistentLayerTemplateType as a6, type PhotoGridInput as a7, type Position as a8, type ProgressIndicatorConfig as a9, type ThemeSchemaVersion as aA, type ThemeSeedColors as aB, type ThemeStyle as aC, type ThemeTypography as aD, type TitleBlockInput as aE, type TitleCaptionConfig as aF, type TwoColumnInput as aG, VIEWPORT_PRESETS as aH, type VideoLayer as aI, type VideoPullQuoteInput as aJ, type VideoWithCaptionInput as aK, type ViewportConfig as aL, type ViewportOrientation as aM, type ViewportPreset as aN, type VignetteConfig as aO, applySurface as aP, calculateDuration as aQ, calculateFontScale as aR, createTemplateContext as aS, createTheme as aT, getAspectRatioString as aU, getBlockAtTime as aV, getCaptionAtTime as aW, getDocPlaybackDuration as aX, getLayoutHints as aY, getRegisteredThemes as aZ, getSafeTextBounds as a_, type PullQuoteInput as aa, type QuoteBlockInput as ab, type RawLayersInput as ac, type RenderStyle as ad, type RightFeatureInput as ae, type ScheduledClip as af, type SectionHeaderInput as ag, type ShapeFilter as ah, type ShapeLayer as ai, type ShapePattern as aj, type SolidBackgroundConfig as ak, type StartBlockConfig as al, type StatHighlightInput as am, type SurfaceScheme as an, THEME_SCHEMA_VERSION as ao, type TableLayer as ap, type TableLayerStyle as aq, type TemplateBlock as ar, type TemplateContext as as, type TemplateFunction as at, type TemplateRegistry as au, type TextLayer as av, type TextStyle as aw, type Theme as ax, type ThemeColorPalette as ay, type ThemeColorScheme as az, type AmbientGradientConfig as b, getTwoColumnPositions as b0, getViewport as b1, getViewportOrientation as b2, isPersistentLayerTemplate as b3, isTemplateBlock as b4, scaledFontSize$1 as b5, lookupRegisteredTheme as b6, registerTheme as b7, resolveMediaSchedule as b8, scaledFontSize as b9, unregisterTheme as ba, validateDoc as bb, type Animation as c, type AnimationType as d, type AudioBookmark as e, type AudioSegment as f, type AudioTimingData as g, type AudioTrack as h, type BlockConnection as i, type BorderStyle as j, type CaptionTrack as k, type CaptionWord as l, type ColorScheme as m, type ComparisonBarInput as n, type CornerBrandingConfig as o, type CustomTemplateDefinition as p, DEFAULT_DOC_FONT as q, DEFAULT_TITLE_FONT as r, type DataTableInput as s, type DateEventInput as t, type DeepPartial as u, type DefinitionCardInput as v, type DiagramBlockInput as w, type Doc as x, type DocBlock as y, type DocDiagnostic as z };